Night Owl 6

home *** CD-ROM | disk | FTP | other *** search

/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 020a / ansip21b.zip / ANSIPLAY.DOC < prev next >

Wrap

Text File | 1991-08-15 | 62KB | 1,491 lines

ANSIPLAY vs. 2.1 - Copyright 1991, J. Ibarra ALL RIGHTS RESERVED U S E R ' S M A N U A L (updated 08/12/91) INDEX: PAGE NO. ------------------------------------------- -------- Copyright Notice and Regulations . . . . . . . . 2 Introduction . . . . . . . . . . . . . . . . . . 3 Files included with the program. . . . . . . . . 4 Printing the manual. . . . . . . . . . . . . . . 5 How ANSIPLAY works . . . . . . . . . . . . . . . 5 INSTALLATION program . . . . . . . . . . . . . . 6 Editing your ANSI file . . . . . . . . . . . . . 6 Using alternate characters in place of ESC . . . 7 Music string syntax. . . . . . . . . . . . . . . 7 Music string contents. . . . . . . . . . . . . . 7 Music codes / Sound codes definition . . . . . . 8 Using Music Codes. . . . . . . . . . . . . . . . 9 Using Sound Codes. . . . . . . . . . . . . . . . 9 Variation in Music String formats. . . . . . . . 11 Music string Tutorial (TUTOR.BAT). . . . . . . . 11 Making the music strings invisible . . . . . . . 12 Using ESC/Music Note characters during editing . 13 Getting familiar with ANSIPLAY . . . . . . . . . 13 ANSIPLAY command syntax (and options). . . . . . 13 File viewing with /L option. . . . . . . . . . . 14 Reinitializing the display screen (ANSIPLAY.CLS) 15 Removing music strings (MUSCSTRP.EXE). . . . . . 16 How ANSIAUTO works (slide-show). . . . . . . . . 16 Running ANSIAUTO . . . . . . . . . . . . . . . . 17 Using PLAY.EXE (music string player/editor). . . 17 Registering ANSIPLAY . . . . . . . . . . . . . . 19 APPENDICES . . . . . . . . . . . . . . . . . . . 20-24 * Page 1 * First of all, let me get this over with... COPYRIGHT NOTICE AND REGULATIONS -- Please read !!! -------------------------------- THIS CONDITION STATEMENT SUPERSEDES ALL PREVIOUS AGREEMENTS. ANSIPLAY and included files are NOT Public Domain and they are not free. All copyrights to ANSIPLAY and included files are reserved by the author, Julie M. Ibarra, and are protected by United States Copyright Laws. ANSIPLAY is distributed under the ShareWare concept. To continue development/enhancement of ANSIPLAY to make it the quality program you expect depends solely on the honesty and integrity of YOU, the ANSIPLAY user. The Copyright notice which is displayed after each file is viewed will not be shown on registered versions of ANSIPLAY. Non-registered users of this program are hereby granted a limited license to use ANSIPLAY and included files to and see if it fullfills their needs. If you intend to use ANSIPLAY or included files for usage other than this limited purpose you are required to register each copy used. Use of ANSIPLAY by non-registered people outside of this limited license is prohibited. Violators of the license will be held accountable for their actions in a Court of Law and may face financial penalties and/or imprisonment. User's are free to use ANSIPLAY and included utilities for a trial period of 30 days. If after 30 days you decide to keep the program, you must register your copy by sending the required payment to the author. Failure to register your copy after 30 days is in direct violation of copyright laws. Neither ANSIPLAY nor any of the included program files nor documentation may be altered in any way. Non-registered versions of ANSIPLAY (and included files) may be distributed freely in unaltered form provided that NO CHARGE is made for the program itself (postage and disk costs excluded). All files and documentation must be included. System Operators may make ANSIPLAY available for download only if the above conditions are met. Distributors of "Public Domain", "Shareware", and/or User Supported software may distribute ANSIPLAY and included files subject to the above conditions only after obtaining WRITTEN permission from The author, Julie M. Ibarra. This product is provided "AS IS" WITHOUT WARRANTY OF ANY KIND. The entire risk as the results and performance of the PRODUCT is assumed BY YOU. * Page 2 * In NO event shall the author, nor employees of the author be liable for any damages whatsoever (including without limitation damages for loss of business profits, business interuption, loss of business information and the like) arising out of the use of or inability to use this product even if the author has been advised of the possibility of such damages. This license does not apply to the REGISTERED version of ANSIPLAY. Different conditions and agreements pertain to the REGISTERED version of ANSIPLAY, and are included with all registration orders. INTRODUCTION ------------ If you have this program, more than likely you are already familiar with ANSI control sequences. But just for sake of reference, here's a few more details about what ANSI is and how it works. ANSI (American National Standards Institute) control sequences are simply sets of characters which, when put together, will enable computer-users to have extended control over their display screen. This extended control is given by DOS's device driver, ANSI.SYS, which reads these sets of characters, interprets them, and then processes the commands by moving the cursor positions, changing screen colors, etc. They also will allow your monitor to display the extended ASCII character set (Decimals 128 - 255). These sets of characters are referred to as Escape Command Sequences. In other words, a sequence of commands preceeded by an Escape character (Decimal Character 27). Each computer system processes these command sequences at different speeds...for example, an AT will processes much faster than an XT. There are several software packages which allow the user to edit and save these command sequences into a file (called an ANSI file) without having to know the actual command sequences. Some of these (Such as Shareware's "THE DRAW") will allow you to specify the speed of which you want the ANSI file to be displayed. Once the ANSI.SYS device driver is installed in DOS (Disk Operating System), these ANSI files may be displayed by simply typing a DOS command something like: TYPE FILENAME.ANS Installation of ANSI.SYS is discussed later in this manual. Until now, the ANSI files have had one drawback...they have screen control, but no sound. * Page 3 * ANSIPLAY was developed for the purpose of adding music/sound ability to ANSI files. ANSIPLAY is NOT intended to be an ANSI editing program such as the well known Shareware program "TheDraw" which enables on-screen selection of colors, cursor positions and movement, etc., but rather ANSIPLAY is intended allow the user to use ANY ANSI file and, by adding a few extra escape command sequences (we'll call them music codes), enable the integration of screen display and music/sound/pauses to it. Once these music codes are added to the file (by use of most any text editor), the simplest command used to display/play them would replace the 'TYPE' command with 'ANSIPLAY', thus something like: ANSIPLAY FILENAME.ANS Later in this manual is a more detailed breakdown of command syntax and additional options available with ANSIPLAY. One thing to remember: Adding music strings to the file is kind of like putting icing on the cake...it's the final touch to your ANSI file. You can't re-bake the cake once the icing's been put on it, and you can't reconstruct the ANSI file with an ANSI editor (such as "The Draw") with the music strings in it. The reason being that the editor will try to interpret the escape sequences containing music strings as text, therefore displaying it to screen. You CAN however, remove the music strings using MUSCSTRP.EXE, to make the file compatible for the ANSI editor again. (Refer to the section on "Removing Music Strings".) A text editor, of course will interpret ALL characters as text so there's no problem there. FILES INCLUDED -------------- Files included with this package are as follows: ---Program Files--- INSTALL .EXE - Installation program (please read INSTALL.DOC) ANSIPLAY.EXE - Program to read/display/play ANSI files. ANSIAUTO.EXE - Program to automate ANSIPLAY.EXE into a slide-show. PLAY .EXE - Allows you to play a music string from the DOS prompt. MUSCSTRP.EXE - Removes music strings from your ANSI files. GO .BAT - An Introduction to the entire program package. TUTOR .BAT - A brief tutorial on some of ANSIPLAY's more advanced features. (Read this manual first.) * Page 4 * ---Documentation--- INSTALL .DOC - Information of using the INSTALLation program. OVERVIEW.DOC - A quick look at most of ANSIPLAY's features. ANSIPLAY.DOC - User's Manual (This documentation). ANSICODE.TXT - Listing of ANSI control sequences available. MUSICODE.TXT - Listing of Music and Sound codes available to be used with ANSIPLAY.EXE. ORDER .FRM - Registration Form to purchase your registered and most current version of ANSIPLAY. UPDATE .TXT - Info. about changes made from prior versions. BBS .TXT - Some pointers for BBS user's ---Data Files--- ANSIAUTO.DAT - Sample Data file used with ANSIAUTO.EXE. INTRO .ANS - Data file used with GO.BAT TUTOR .ANS - ANSI file used with TUTOR.BAT XMASTREE.ANS - Demonstration ANSI file (using music codes) FAUCET .ANS - Demonstration ANSI file (using sound codes) SEA .ANS - Demonstration ANSI file (using music and sound codes) PRINTING THE MANUAL ------------------- The installation program (INSTALL.EXE) will allow you print any/all documentation included with the ANSIPLAY program package. If you'de rather print the manual from the DOS prompt, log onto the drive/directory in which this file (ANSIPLAY.DOC) exists, and type COPY ANSIPLAY.DOC PRN. All other documentation files/order form may be printed the same way by using different filenames. Form-feeds are included at the end of each text file. HOW ANSIPLAY WORKS ------------------ When you run ANSIPLAY, you will specify the filename of the file you want to be displayed/played. ANSIPLAY will read the file and display it to the screen using the ANSI.SYS device driver, while at the same time, searching for music codes which tell ANSIPLAY what music notes/sounds to play. The music codes are NOT ANSI escape command sequences, but rather they are interpreted and processed by ANSIPLAY. ANSIPLAY will be just slightly slower than DOS's TYPE command since it must search the text for each music string and process it accordingly. DOS's TYPE command will process the strings as text. The text may be made hidden (invisible) by embedding additional escape command sequences in the ANSI file. (Refer to the section on "Making the music strings invisible".) * Page 5 * Shareware versions will then display a short message in ANSI to remind users that the version in not registered. This message is not displayed with registered versions. INSTALLATION (INSTALL.EXE) -------------------------- Installation will allow you to do the following... 1. Installation of your ANSI device driver into your CONFIG.SYS file. 2. Setting a PATH in your AUTOEXEC.BAT file (for use with ANSIPLAY program files). 3. Creating/Updating your ANSIPLAY.CLS file. 4. SETting an environment variable via your AUTOEXEC.BAT file (for use with the file ANSIPLAY.CLS) 5. Option to print documentation file(s). To run the installation program, type INSTALL at the DOS prompt. A two-page document (INSTALL.DOC) gives more information on these options. To print INSTALL.DOC while in the INSTALL program, answer Yes when asked..."Print the file INSTALL.DOC now ?". About your ANSI device driver ----------------------------- Many programs use ANSI control characters, but if the device driver ANSI.SYS is not installed before comming accross them, you'll just get a lot of funny looking characters that don't mean much. The ANSI device driver "ANSI.SYS" is included in your own DOS files. The installation program will determine whether or not the driver is already installed. If you're still wondering, you can type 'ANSIPLAY' at the DOS prompt. When the copyright message is displayed, if you see color, the driver is installed. If you get a menagery of strange characters on the screen, the driver is NOT installed. Once the ANSI device driver is installed into your CONFIG.SYS, it will be loaded automatically each time you boot up. If you wish to install the driver manually rather than using the included installation program (INSTALL.EXE), consult your DOS user's manual for information on how to do this. EDITING YOUR ANSI FILE ---------------------- If you are starting from scratch, you may want to look into an ANSI screen editor such as the Shareware program "TheDraw". Without such a program, ANSI file creation can be tackled, but it would be extremely tedious and time-consuming at best. * Page 6 * Your DOS user's manual will explain the escape control sequences used with ANSI.SYS. There is also a reference listing included in the file ANSICODE.TXT (see section on "printing the manual"). One example would be, to set the foreground color to bright yellow on a blue background... ESC[44;1;33m Unless you're very familiar with these escape sequences, it can be a bit like learning a foreign language. USING ALTERNATE CHARACTERS IN PLACE OF ESC ------------------------------------------ If for some reason the ESC character is stripped, for instance by a BBS that does not allow extended ascii characters during file transfers, etc., ANSIPLAY will still process the file: ANSIPLAY will detect the non-existance of the ESC characters when none are found within the first block of characters read. Then it will determine the alternate character automatically by locating the first "[" occurance in the file and using the character prior to the "[" as the alternate character. ANSIPLAY will then auto- matically replace every occurance of this alternate character with the ESC character. If character replacement is used this way, the display rate may be slightly slower, but barely noticeable. MUSIC STRING SYNTAX ------------------- Once your ANSI file has been created, all that's left to do to make it musical is add a few extra escape command sequences, for example, a music code of... ESC[MF O2 CDEC CDEC EFG.... EFG....(music note) would play the introduction to the song "Frere Jacques". Below is a breakdown of how the music strings are to be used. By using your own text editor, you can insert these codes into any desired location in your ANSI file, then play it back using ANSIPLAY.EXE. (see section below on using ESC character during editing) MUSIC STRING CONTENTS --------------------- The word "string" simply means a set of characters (including spaces and ascii characters) strung together. * Page 7 * There are 3 sections to a Music string, broken down as follows: ESC[MF CDEC CDEC EFG (music note) ------ ------------- ------------ 1 2 3 All music strings must be prefixed with ESC+"["+"MF" (or "MB") in upper-case text, and final character must be a (music note). 1. Music strings are prefixed with the ESCape character followed by a [ character (just like ansi escape control sequences), and then followed by MF (for Music/Sound to be played in Foreground) or MB (for Music to be played in Background). *Or for a shortcut you may use ESC[M which will be treated as ESC[MF. *** Note that the ESC above actually resembles the ESCAPE character (Decimal CHR$(27)) and not the actual letters E S C. Refer to the section on "Using the ESC character during editing". 2. The middle part of the string can be 1 of 2 types of commands... Music Codes ----------- a) the actual <notes, octaves, etc> specification (for musical tunes). Spaces and carraige returns (CR-LF) are ignored. This portion of the music string can be of any size length. -or- Sound Codes ----------- b) a <tone frequency; duration; cycles; delay; vari> specification (for other sound tones and repeated cycles of sound tones). Parameters must be separated by semi-colons. Details on these codes and command syntax will be discussed shortly. There is also a reference listing of the codes in the file MUSICODE.TXT (see section on "printing the manual"). 3. The final(music note) (Decimal CHR$(14)) is a must. This tells ANSIPLAY where the music string ends. The (music note) character can be entered on most text editing programs by holding down the [ALT] key, then typing the number 14...similarly to entering the ESC character. (See "Using the ESCape character during editing") * Page 8 * ------------------------------- USING MUSIC CODES ------------------------------- ESC[MF <music notes and commands)> (music note) (MB may be used in place of MF) Example: ESC[MF CDEC CDEC EFG (music note) MF will play the music in the foreground, or in other words will stop displaying temporarily until the music string is played completely. MB will place the music string into a buffer, allowing the program to execute while the music string is playing in the background. The number of notes that can be played in the background at one time varies according to the particular machine. Maximum number of notes that can be played in the background at one time is 32. When there are more notes to be played than the buffer will hold, the display will temporarily pause until the remainder of the music string is processed. More than 1 MB statement in the music string will cause the music to be played sequentially (NOT simultaneously.) In other words, you cannot play 2 or 3 strings of music simultaneously. If a carraige return (CR-LF) is needed within the music string, ANSIPLAY will ignore it and just continue playing. This feature was developed so that user's could use L-O-N-G strings of music without interruption. A breakdown of MUSIC CODES available are listed in the file MUSICODE.TXT. (refer to section on "Printing the Manual"). You may also consult your DOS user's manual under the section on BASIC's "PLAY" statement. See the demonstration ANSI files included with this package for some examples of how MUSIC CODES may be used. ----------------------------------------------- USING SOUND CODES (IN PLACE OF MUSIC CODES) ----------------------------------------------- In place of music codes, you may use numeric values for FREQENCY, DURATION, CYCLES, DELAY and VARIATION to create sounds that are not available with musical code syntax. Another way to use them is to place them next to music strings that contain music codes to add glissando, rythmatic sounds, tapping, beeping, or whatever sounds you'de like to create. A music string containing SOUND CODES would look like this: ESC[MF <FREQ; DURA; CYCLES; DELAY; VARI> (music note) * Page 9 * Example: ESC[MF 100;5;5;10;-5 (music note) The <> brackets are not to be typed. They are only there for display purposes to you can see where the <SOUND CODES> are to be placed. Since SOUND CODES are processed differently from MUSIC CODES, SOUND will always be played in foreground regardless of "MF" or "MB" specification. SOUND CODE Parameters must be separated by semicolons. Minimum/Maximum values and descriptions are as follows: FREQUENCY : a numeric value from 37 to 32,767 Frequency is the desired frequency in hertz. This allows more control over the pitch of the tone than what is available with music codes. DURATION : an numberic value from 0 to 65,535 Duration is how long the tone should play, measured in clock ticks. There are 18.2 clock ticks per second regardless of CPU speed. CYCLES (optional) : an integer from 0 to 9,999 Cycles is the number of times to repeat the frequency/duration. DELAY (optional) : an integer from 0 to 999,999,999 Delay is the length of pause between cycles. ANSIPLAY will count from 0 to DELAY before proceeding. The DELAY time lapse will vary among computer systems. (My XT NEC V20 averages 723 counts per second) If the [ENTER] key is hit during execution of a DELAY, the delay will be ended. VARIATION (optional): an numeric value from -9,999 to 9,999 Variation will change the FREQUENCY each time the tone is repeated using the CYCLES variable. FREQUENCY will use it's current value, add the VARIATION value to itself (per cycle) to get a new FREQUENCY, then play the new FREQUENCY. A negative value used for VARIATION will make the FREQUENCY decrease; a positive value will make the FREQUENCY increase. If the new FREQUENCY is too low or too high, exceeding its playable limits (minimum of 37 to maximum 32,767) then the VARIATION value will be changed to reverse itself (from positive to negative, or from negative to positive). A "*" wildcard may be used in place of a value, which will make the play function select a value at random between -999 and 999. * Page 10 * Any non-integer numbers used for CYCLES or DELAY will be converted to integers automatically. SOUND CODES are interpreted and executed as they are read, therefore requiring them to be played in the foreground. The interpretation process is basically structured like this: :START_OF_CYCLE Play Frequency/Duration Add DELAY if applicable Change Frequency if VARIATION is used Go to :START_OF_CYCLE (Loop for number of CYCLES specified) See the demonstration ANSI files included with this package for some examples of how SOUND CODES may be used. VARIATION IN MUSIC STRING FORMATS --------------------------------- Although there are several ANSI viewers on the market which support music, there is currently no "standard" as to the format used with the music strings. Some viewers will not support music strings of a length longer than 71 characters. Some viewers use a Prefix with ESC[M while others use ESC[MF or ESC[MB. Some viewers will support music, but only if it's the final text of the file, not if it's integrated into the file. Many viewers will not support one continuous music string thus requiring the string to be broken into segments. This may cause the music to sound choppy when it's played. ANSIPLAY will support all of the above formats, along with unlimited music string length and sound codes. Though if you wish to use another viewer, you will need to consult the documentation included with the program regarding the required format for that program. Sound codes, however, will most likely not be supported as they are a new concept just released by the author of ANSIPLAY. Hopefully, they will soon be supported by other ANSI viewers as well. TUTORIAL FOR MUSIC STRINGS ------------------------- Now that you are somewhat familiar with music code and sound codes...you can see a more detailed explaination of some of the more advanced way in which these codes can be used by typing TUTOR at the DOS prompt. This will ansiplay the file TUTOR.ANS which will give some examples and define how they are used. Then it will bring you into ANSIAUTO to display the demonstration ANSI files which are included with the program package. * Page 11 * MAKING THE MUSIC STRINGS INVISIBLE ---------------------------------- Since the music strings are interpreted by ANSIPLAY while the file is being read, the music string text is not displayed to the screen. However, if you also wish to not display the strings while using DOS's TYPE command to view the file, this may be done by adding a few extra ANSI escape command sequences. Before the music code, add: --------------------------- ESC[0m ESC[s ESC[?;1H ESC[8m (text is upper/lower-case sensitive) Spaces should not be typed...they are only here to make the codes easier to read. Here is the breakdown: ESC[0m Turns all attributes off. If the display is in high intensity mode, this is required. ESC[s Store the current cursor position. ESC[?;1H Wherein ? would be the current row number. Any row from 1-24 may be used, however if the cursor has to move all the way across the display, it may cause blinking. "1" sets the cursor at column 1. Even though the text will be invisible, it will still be printed to screen. If the end of screen is reached, the text will be wrapped around to the next row. If you are using long music strings and it is causing the display to eject upward, you may try using shorter strings of about 75 characters or so at a time. ESC[8m This will make the music string invisible when it is written to screen. Otherwise it will be written to screen in the current color attributes. After the music code, add: -------------------------- ESC[u ESC[0m (text is upper/lower-case sensitive) Spaces should not be typed...they are only here to make the codes easier to read. Here is the breakdown: ESC[u Moves the cursor back to the location it was at when the last ESC[s command (store cursor) was used. ESC[0m Returns to normal mode. Turns off invisible attribute. * Page 12 * The entire set of commands would look like this... ESC[0m ESC[s ESC[?;1H ESC[8m ESC[MF<music string> (music note) ESC[u ESC[0m Remember, making the music codes invisible is only necessary if you wish to use an ANSI display program other than ANSIPLAY. USING THE ESCAPE CHARACTER DURING EDITING ----------------------------------------- If you use DOS's edlin command for text editing, you will not be able to enter an ESCape character (ASCII character CHR$(27)), since hitting ESCape will type a \ character instead. Most word/text editing programs will allow you to enter an ESCape character by holding down the [ALT] key, then simultaneously entering the number 27. Usually this is displayed as a left arrow character. (Music note would be [ALT] + 14). If you use a commercial word processor such as Word Perfect or Word Star, the text must be saved as plain ASCII text format. Otherwise there will be extra printer codes embedded into the file which will mess up the whole thing. If you do not have a text editor, I recommend a Shareware program called QEDIT. It's very powerful and does allow extended ASCII characters. The (music note) character may be entered the same way as the ESCape character by using the decimal 14 instead of 27. GETTING FAMILIAR WITH ANSIPLAY ------------------------------ To see the demonstration files, at the DOS prompt type DEMO. To get familiar with the program and included files, type GO. RUNNING ANSIPLAY ---------------- Syntax from the DOS prompt is as follows: ANSIPLAY [Path\FileName DelaySeconds] [/Option Flags] (If no parameters/options are used, ANSIPLAY will default to the /L option as described below, which will automatically bring up a file(s) listing menu to work from.) Parameters are: [Path\Filename] is the drive\directory\filename of the ansi file you wish to display/play. Wildcard characters * and ? are not supported. If no filetype is given, then ANSIPLAY will append the filetype of ".ANS" to the filename. * Page 13 * If no drive\path is given, then ANSIPLAY will search the currently logged (default) drive\path for the ANSI file. If the /L option is used (as describes below), only use a [Drive:\Directory\] Path specification. Any filename.type specified will be ignored. [ DelaySeconds] is the number of seconds to delay program execution. This option is used for ANSIAUTO (automatic slide show present- ation of ansi files). If this option is used, the number of seconds must be preceeded with a space ( ). While using ANSIAUTO, there will be a pause of DelaySeconds between displays of ANSI files. [Options] are as follows: <Multiple option flags may be used in any order> /C (ClearScreen) clears the screen before displaying the ANSI file. /H (Help) Displays a brief help screen for ANSIPLAY syntax. /Q (Quiet) Disables the music and sound during display of the ANSI file. /Q option does NOT disable a DELAY parameter (Sound Code) if one exists. /D (Delete) Prompts user if ANSI file is to be deleted after display. This option was designed for those who use off-line mail readers. The mail read can save the message to a temp- orary file, and then Shell out to DOS to ANSIPLAY it. Then the /D option will allow you to delete the temporary file. After the file display has been completed, if you decide not to delete the file, ANSIPLAY will ask if you want to rename the file. At this time, if you answer "Y" (yes), you will be asked for the new filename. (Note: the option to Delete/Rename will be bypassed if the display is interrupted by hitting the ESCape key). When asked to Delete or Rename, hitting the [ENTER] key will assume the default of "[N]o". /L (List) will create a listing of all files with the extension of ".ANS" that are located in the specified drive\directory. If no drive\directory is specified, then the current drive\directory will be used. When using the /L option, do NOT enter any file specifications such as *.*, *.ANS, but rather specify the drive\directory only, for example: * Page 14 * ANSIPLAY C:\ANSI /L -or- ANSIPLAY C:\ANSI\ /L A listing will then be alphabetized into a box which you can use page up/down to view. To select the file you want to ANSIPLAY, simply type in the number which is found to the left of the file name and hit [ENTER]. After the file is displayed/played, the file selection screen will return for your next selection. The /L option will support up to 475 file names. If more than 475 records are found, they will not be acknowledged and the message "475+ records found" will be displayed. The "+" notates the overage. Options Flags /C /D and /Q may be toggled on/off by hitting... C - for ClearScreen toggle D - for Delete toggle Q - for Quiet toggle You may also use the [F1] function key to change drive\directory of the files you want to view. (This option is only available in registered versions of ANSIPLAY). If you change to a drive\directory is invalid, the program will be terminated. The Delete option will allow you to view the file before asking if you want to delete it. If you answer No, you will then be given a chance to rename the file. Note: the /L option will not work with ANSIAUTO, but rather, it will be ignored. If you want the freedom to use the ANSIPLAY command while logged onto ANY drive\directory, just add the name of the directory in which ANSIPLAY exists to DOS's search PATH. (Consult your DOS user's manual for more information on how to do this). This can also be done by using the installation program (INSTALL.EXE). To exit ANSIPLAY at any time, press the [ESC] key. REINITIALIZING THE DISPLAY SCREEN (ANSIPLAY.CLS) ------------------------------------------------ Once ANSIPLAY has completed displaying/playing the ANSI file, there may have been several changes made to the screen display such as screen mode, color attributes, etc. To reinitialize the display to your desired settings, simply create a file called ANSIPLAY.CLS containing the desired ANSI escape command sequences. ("CLS" for "Closing Screen") * Page 15 * This can be done with the installation program (INSTALL.EXE) or by using your own text editor. This file is optional. If ANSIPLAY.CLS file does not exist, then the only reset code which is automatically executed is ESC[0m which turns all attributes off and returns to normal display. If the file ANSIPLAY.CLS does exist, the ESC[0m will be ignored regardless of whether the file contains escape command sequences or is empty. An example of how this file might be used is to: ESC[=3l 'reset the screen mode to 80 x 25 color ESC[0m 'all attributes off, normal display ESC[44;1;33m 'set colors: bright yellow on blue background ESC[2J 'clear screen thus the contents of ANSIPLAY.CLS would actually be: ESC[=3lESC[0mESC[44;1;33mESC[2J (ESC resembles the actual ESCape character which must be used). Refer to the files ANSIPLAY.DOC and ANSICODE.TXT for more details on the actual ANSI codes to use. It is recommended that no other text, music codes, etc. are included in this file, since they will be displayed after each ANSI file display. REMOVING MUSIC STRINGS (MUSCSTRP.EXE) ------------------------------------- If wish to remove all existing music strings from the ANSI file, at the DOS prompt type MUSCSTRP FILENAME.ANS MUSCSTRP (Music Strip) will create a new file using the same filename, but with the file extension of .NEW The MUSCSTRP program must be able to locate ANSIPLAY.EXE either in the current directory, or in DOS's PATH setting. HOW ANSIAUTO WORKS ------------------ ANSIAUTO will read the contents of the data file you specify on the command line. (See "RUNNING ANSIAUTO" regarding DataFile Structure) Once the data is loaded into memory, ANSIAUTO will shell to DOS and execute the ANSIPLAY command (with any optional parameters which are specified) per file. Each file will be displayed (played) in sequence. If a DelaySeconds parameter was specified, the program will pause * Page 16 * after the file is displayed for the set number of seconds, and then continue onto the next file. Once all the files have been displayed, ANSIAUTO will start the sequence over again (and again...). RUNNING ANSIAUTO ---------------- Syntax is as follows: ANSIAUTO DRIVE\PATH\FILENAME.DAT If no filetype is given, then ANSIAUTO will append the filetype of ".DAT" to the filename. To EXIT ANSIAUTO, hit the ESCape key on the keyboard. ANSIPLAY will not respond until the file display/play is completed. At that time, the program will exit and return to DOS. Data file structure ------------------- Each line of the file contains the same specifications as would normally be entered on the DOS command line when executing ANSIPLAY. An example datafile might look like this: C:\ANSI\MERMAID.ANS,3 /C D:\DRAW\CASTLE.ANS,2 /C C:\UTILS\FIREMAN.ANS /C /Q . . . . . . etc. etc. etc. As mentioned before, unregistered versions of the program will display the "ANSIPLAY [Unregistered Version] Copyright 1991, J. Ibarra" message after each file is display/played. Registered versions do not have this message. Maximum number of files that can be used for slideshow is 30. If the data file contains more than 30 filenames, they will be ignored. If 30 is not enough, let me know and I can increase it. USING PLAY.EXE (Music String Player/Editor) ------------------------------------------- Syntax is: PLAY [options] <* MUSIC CODES or SOUND CODES> *The prefix of ESC[ and suffix of (music note) are not required on the DOS command line. Wherein [options] are: <* MUSIC/SOUND CODES> - plays the <music/sound codes> /E - for music string editor /E <* MUSIC/SOUND CODES> - loads <music/sound codes> into the editor /R - to repeat last-played music string /R /E - loads last string played into editor [options] may be in any order * Page 17 * If you want to experiment with music/sound codes, PLAY.EXE is the quickest way to do it. PLAY.EXE has two ways of working... 1: It will allow you to play music codes directly from the DOS prompt. 2: It will allow you to edit, then play, the re-edit, etc. music strings, and write to file. If MF or MB is not specified, default is set for MF. See sections on "Using Music Codes" and "Using Sound Codes" for more information on Music String Syntax. --- TO PLAY THE MUSIC CODES DIRECTLY FROM THE DOS PROMPT --- Playing a music/sound codes directly from the DOS prompt is easy. An example would be, to hear the beginning of Frere Jacques (ESC[MF O2 CDEC CDEC EFG.... EFG....(music note)), at the DOS prompt, you would type the command line: PLAY O2 CDEC CDEC EFG.... EFG.... or to hear a bomb dropping, you might type: PLAY 900;1;120;;-5 Note that the > and < characters cannot be used from the DOS prompt because DOS will interpret these as piping character. Optionally you can set the octave with On wherein n is the value (0-6) of the Octave you desire. Default octave is 4. Before playing the music string, PLAY.EXE will check for any letters that are NOT valid music code characters. If an invalid letter is found, you will receive the error message "Illegal play string". Play will then take you directly into the music string editor. If the string has a length greater than 73 characters, the string will be trimmed to 73 characters so that it will fit into the editor. If this happens, a message will appear to notify you. /Repeat option (from the DOS prompt): ------------------------------------- PLAY will automatically store the last music string played ,if one exists, to a temporary file named PLAY.##. If no music string exists upon exiting PLAY, the last music string will NOT be overwritten with a blank music string. This way if you decide you don't want to keep your edited changes, you can simply hit [CTRL]-[Backspace] to erase them, then upon exiting PLAY there will be no changes made to the PLAY.## file. The /R option will allow you to repeat the music string by either using it at the DOS prompt, or loading it into the music string editor (see below). To repeat the last string from the DOS prompt, type PLAY /R. If the /R option is used, any included <music string> on the DOS command line will be ignored. * Page 18 * --- TO USE THE MUSIC STRING EDITOR --- The music string editor is the more useful feature of PLAY.EXE. It will allow you to play Music Codes or Sound Codes, then edit them on the screen, replay them, etc. Once you have the music/sound codes exactly as you want them, you can then save them to file. The /E option will activate the editor. At the DOS prompt, you may optionally enter the music string you wish to edit . Music String Editor commands are as follows: Move Cursor: LEFT/RIGHT arrow keys Delete Character above cursor: DEL key Move cursor to 1st character: HOME key Move cursor to end character: END key Erase entire music string: CTRL+Backspace Write music string to file: CTRL+W Toggle prefix of "MF" or "MB": TAB key Exit PLAY.EXE: ESC key If the music string contains characters which cannot be played, you will receive an error message "Illegal play string". It will then return to the editor so you can make your changes. The write option will write the music string to a file named "PLAY.MUS". (Note this is a different file from the PLAY.## temporary file). The ESC[MF prefix and (music note) character suffix will automatically be added. If there are pre-existing music strings, the new music string will be appended (not overwritten). /Repeat option (with the Editor): --------------------------------- The /R option will allow you to (Repeat) load the last-played music string into the editor by typing PLAY /R /E at the DOS prompt. If the last-played music string is longer than 73 characters in length, PLAY will trim the string to 73 characters so it will fit into the editor. (If the last character is an "M", it too will be trimmed to avoid sending the PLAY function into oblivion). If the /R option is used, any included <music string> on the DOS command line will be ignored. REGISTRATION OF ANSIPLAY ------------------------ User's who register their copy of ANSIPLAY will receive a new copy of the most current version of the program and included utilities. * Page 19 * Advantages of registration are: 1. Registered versions will NOT interrupt the ANSI display with the copyright message at the bottom of the screen. 2. The [F1] function used to change Drive\Directory will be fully functional from the file listings menu. 3. Registered users will automatically be notified when an updated version is released. 4. Registered users may purchase future updated versions for only $5.00 each (plus postage and handling). If you wish to register your copy, you may print the registration form by typing COPY ORDER.FRM PRN at the DOS prompt. Fill out the registration form and enclose required payment in check or money order (no cash please) and mail to: Julie M. Ibarra P.O. Box 710727 Santee, CA 92072-0727 To print the registration form, at the DOS prompt, type: COPY ORDER.FRM PRN --------------------------------------------------------------- ========== APPENDIX I - TROUBLE SHOOTING (INSTALLATION) =========== Problem: When I entered the letter of the boot drive, the program said "Logging onto boot drive..." and never returned. Reason: INSTALL will try to access the drive you specified. If the drive is invalid or unaccessible, the program will be sent into infinity. Solution: Reboot, and try again...this time being sure the drive is valid and accessible. Problem: When INSTALL went to access my CONFIG.SYS, AUTOEXEC.BAT or ANSIPLAY.CLS files, it returned an error message. Solution(s): - Be sure that the CONFIG.SYS and AUTOEXEC.BAT files are on the drive\directory you specified. * Page 20 * - Be sure the drive\directory you specified is valid and accessible. Files that are read-only are not accessible and will return an error message. - Be sure the specified drive has enough disk space to write the updated data onto. Problem: When I reboot, there was an error in CONFIG.SYS file. Reason: INSTALL.EXE seaches the CONFIG.SYS file for an exact match of drive\directory\filename in which the ANSI device driver exists. The device driver may have already been installed under a different drive\directory than the one you specified. Since the path's do not match, INSTALL.EXE assumes that the driver is NOT installed therefore installing it twice. When the system is re-boot, the driver is installed twice thus causing the error. Solution: Use your text editor to remove the incorrect text line. Problem: When entering the drive\directory to locate a file, the program sometimes will not accept my keyboard input. Reason: The program has a built-in feature which checks for proper pathname syntax during user-interaction. For example, if during a "\" character creates a situation where two "\\" characters are found, the program will not accept the improper format. Solution: Turn off INSert mode if necessary (by hitting the INS key), and type it in properly. The automatic syntax checking will be removed in the next updated version to help simplify user input. Problem: When the PATH setting is changed, the new PATH is displayed on screen. Before INSTALL.EXE changes the PATH setting, it tries to find an existing PATH in the AUTOEXEC.BAT file. This is done by searching for the FIRST occurence of the text "PATH " (PATH followed by a space), or "PATH=" (PATH followed by an equal sign. If by fluke chance there is another line of text in the AUTOEXEC.BAT file, INSTALL.EXE will think this was the line to be changed and alter it. Solution: Use your own text editor to fix the line of text which should not have been altered. Then, if you're unsure how to change * Page 21 * the actual PATH setting, just move the line of text which contains the PATH setting to the beginning of the file, and re-run install. ========== APPENDIX II - TROUBLE SHOOTING (MUSIC STRINGS) =========== Problem: I keep getting the error message "Illegal string in PLAY parameters". Solution: Consult the documentation to be sure the values used in your MUSIC CODE's and/or SOUND CODE's are valid. If the problem still persists, and the parameters are indeed valid, contact the programmer. Another Solution: It's possible that the letter O was used in place of the number 0 (zero), or visa-versa in the MUSIC CODE's and/or SOUND CODE's. It's very easy to mix these up. Another Solution: It's possible that the music note characters, [CHR$(14)] was not included in the music string. Consequently, the program will read the entire file until it encounters the music note. If no music note is found, it will append a music note at the end and try to play the string. Problem: Why do I get an "Illegal play string" error? Reason: Something in the play string is not valid. This could be caused by using a note that does not exist such as B#, H, etc.; or using a value which is not within set limits for octave, tempo, etc. such as O7; or using an invalid character which is not a music code/sound code character. Problem: My text editor will not allow me to enter the ESCape char- acter (or music string character) into the ANSI file. Solution: Some editors (though few) do not have this ability. Refer to the section "Using the ESC character during editing". If this still doesn't help...if your editor has a cut-and-paste feature, you might try duplicating the ESC character this way. If all else fails, try another editor. There is a fantastic Shareware text editor that is very intelligent called "QEDIT". ========== APPENDIX III - TROUBLE SHOOTING (ANSIPLAY) =========== Problem: Lots of strange characters (garbage) on the screen. * Page 22 * Solution: Be sure that the ANSI.SYS driver is installed into your CONFIG.SYS file (See section on "About ANSI.SYS"). Problem: The program ignores my efforts to escape during the displaying of my ANSI file. Reason: ANSIPLAY reads and processes large portions of the ANSI file at a time. The output of these portions may be as large as the whole display screen. Since the printing of these portions cannot be interrupted, ANSIPLAY and ANSIAUTO will not respond to using the ESCape key until the entire portion has been processed. Problem: When I use "MB" (Music Background) in the music string, there isn't much difference from "MF". Reason: There are several things happening here...For one, ANSIPLAY must pull out the music strings from the bulk of the file which is being read at one time. The strings must then be processed to produce music/sound/pause's. Secondly, the computer's music buffer will only retain 32 characters at a time. If the music string is larger than 32 characters or if the music buffer is full when the new music string is to be loaded into it, the program has to wait for the buffer to process the characters which have already been loaded to free up more space in the buffer for the remaining characters to be loaded. Thirdly, Sound codes that have parameters for CYCLES and/or DELAY are processed counting from 0 to CYCLES (or 0 to DELAY). The counting procedure is not loaded into the background buffer. When the frequency/duration is played, however, it is then placed into the buffer. The counting feature is extremely fast, but if the set values for these parameters are high, it will slow up the display process slightly. Problem: My file was fine until I edited it...now I get a bunch of garbage when displaying it. Solution: Some word processing programs will add extra printer codes to the file when you "save" the file. Most programs that do this also have an option to "save" as "ASCII" or "DOS TEXT". If so, re-save the file using this option. This will save the contents of the file without adding any other embedded program codes. * Page 23 * ========== APPENDIX IV - TROUBLE SHOOTING (PLAY.EXE) =========== Problem: When I tried to write the music string to file, I keep getting an error..."Unable to save". Reason: There may be one of several causes for this: Disk media format error, not enough disk space or disk write-protected to name a few. ================ APPENDIX V - REFERENCES =============== Programs referenced in ANSIPLAY documentation: AnsiPlay (ShareWare) - by Julie M. Ibarra ANSI viewing utility with music support. QEdit (ShareWare) - by SemWare Text editing program. Silly Little Mail Reader (Shareware) - by Greg Hewgill Off-line mail reader program. TheDraw (ShareWare) - by Keith Miller and Cat Miller ANSI screen drawing utility with animation support. ============== APPENDIX VI - NOTES FROM THE AUTHOR ============== I developed ANSIPLAY to allow users to not only be able to view their ANSI files and play music (which some programs already do), but to also allow support of Sound codes which is not available in any other ANSI viewer. The program is a result of many, many hours and 3 a.m. sessions. Time allowing, I have de-bugged it as much as possible, though bear in mind that I am only ONE person. Should you happen to run accross one of those pesty little "bugs" (even a minor one), please be sure to notify me so that it can be fixed in the next released version of ANSIPLAY. If you have a modem, there is not a "home base" BBS for ANSIPLAY as of yet, but if you have access to a BBS that uses the PC-Relay network, you will be able to leave me a message in the ANSI/GALLERY conference. Or you can call my hang-out...The FileBank BBS in Fallbrook, CA (619) 728-4318. And of course, you can send any correspondence directly to me at: Julie M. Ibarra P.O. Box 710727 Santee, CA 92072-0727 Any comments regarding program features, documentation, present- ation, etc. are always appreciated. --end of documentation--